package com.mldong.modules.sys.api;

import cn.hutool.core.lang.Dict;
import com.mldong.modules.sys.dto.TaskExecutionQueueDTO;

import java.util.Date;
import java.util.List;

/**
 * 任务执行接口
 */
public interface TaskExecutionApi {

    /**
     * 添加任务到执行队列
     * @param taskName 任务名称
     * @param springBeanClass Spring Bean类
     * @param bizId 业务ID
     * @param allowMaxErrorCount 允许最大失败次数
     * @param ext 扩展属性
     * @return 任务ID
     */
    Long addTaskToQueue(String taskName, Class<?> springBeanClass, Long bizId,
                       Integer allowMaxErrorCount, Dict ext);

    /**
     * 更新任务状态
     * @param taskId 任务ID
     * @param taskState 任务状态(1:进行时；2：成功；9：执行失败)
     * @param errorReason 错误原因（可选）
     * @return 是否更新成功
     */
    boolean updateTaskState(Long taskId, Integer taskState, String errorReason);

    /**
     * 取消任务
     * @param taskId 任务ID
     * @param cancelReason 取消原因
     * @return
     */
    boolean cancelTask(Long taskId, String cancelReason);
    /**
     * 根据业务ID取消任务
     * @param bizId 业务ID
     * @param cancelReason 错误原因
     * @return
     */
    boolean cancelTaskByBizId(Long bizId, String cancelReason);

    /**
     * 增加任务错误计数
     * @param taskId 任务ID
     * @return 更新后的错误次数
     */
    Integer incrementErrorCount(Long taskId);

    /**
     * 归档已完成任务到历史表
     * @param taskId 任务ID
     * @param finishedState 完成状态（成功或失败）
     * @param finishedTime 完成时间
     * @return 是否归档成功
     */
    boolean archiveTaskToHistory(Long taskId, Integer finishedState, Date finishedTime);

    /**
     * 从历史归档恢复任务到执行队列
     * @param historyId 历史任务ID
     * @param newAllowMaxErrorCount 新的允许最大失败次数（可选，如果为null则使用原值）
     * @return 新创建的任务ID
     */
    Long restoreTaskFromHistory(Long historyId, Integer newAllowMaxErrorCount);

    /**
     * 获取待执行任务列表
     * @param springBeanClass Spring Bean类
     * @param count 获取数量
     * @return 待执行任务列表
     */
    List<TaskExecutionQueueDTO> getPendingTasks(Class<?> springBeanClass, Integer count);

}
